home *** CD-ROM | disk | FTP | other *** search
/ MacHack 1997 / MacHack 1997.toast / Hacks / Hacks ’96 / VideoFolder 1.0a / Source / MoreFiles 1.4.1 / Search.h < prev    next >
Text File  |  1995-12-21  |  7KB  |  181 lines
  1. /*
  2. **    Apple Macintosh Developer Technical Support
  3. **
  4. **    IndexedSearch and the PBCatSearch compatibility function.
  5. **
  6. **    by Jim Luther, Apple Developer Technical Support Emeritus
  7. **
  8. **    File:        Search.h
  9. **
  10. **    Copyright © 1992-1995 Apple Computer, Inc.
  11. **    All rights reserved.
  12. **
  13. **    You may incorporate this sample code into your applications without
  14. **    restriction, though the sample code has been provided "AS IS" and the
  15. **    responsibility for its operation is 100% yours.  However, what you are
  16. **    not permitted to do is to redistribute the source as "DSC Sample Code"
  17. **    after having made changes. If you're going to re-distribute the source,
  18. **    we require that you make it clear in the source that the code was
  19. **    descended from Apple Sample Code, but that you've made changes.
  20. */
  21.  
  22. #ifndef __SEARCH__
  23. #define __SEARCH__
  24.  
  25. #include <Types.h>
  26. #include <Files.h>
  27.  
  28. #ifdef __cplusplus
  29. extern "C" {
  30. #endif
  31.  
  32. /*****************************************************************************/
  33.  
  34. pascal    OSErr    IndexedSearch(CSParamPtr pb,
  35.                               long dirID);
  36. /*    ¶ Search in and below a directory.
  37.     The IndexedSearch function performs an indexed search in and below the
  38.     specified directory using the same parameters (in pb) as is passed to
  39.     PBCatSearch. See Inside Macintosh: Files for a description of the
  40.     parameter block.
  41.     
  42.     pb            input:    A CSParamPtr record specifying the volume to search
  43.                         and the search criteria.
  44.                 output:    Fields in the parameter block are returned indicating
  45.                         the number of matches found, the matches, and if the
  46.                         search ended with noErr, the CatPosition record that
  47.                         lets you resume a search where the last search left
  48.                         off.
  49.     dirID        input:    The directory to search. If fsRtDirID is passed,
  50.                         the entire volume is searched.
  51.     
  52.     Note:    If you use a high-level debugger and use ioSearchTime to limit
  53.             the length of time to run the search, you'll want to step over
  54.             calls to IndexedSearch because it installs a Time Manager task.
  55.             Most high-level debuggers don't deal gracefully with interrupt
  56.             driven code.
  57.     
  58.     __________
  59.     
  60.     See also:    PBCatSearch, PBCatSearchSyncCompat
  61. */
  62.  
  63. /*****************************************************************************/
  64.  
  65. pascal    OSErr    PBCatSearchSyncCompat(CSParamPtr paramBlock);
  66. /*    ¶ Search a volume using PBCatSearch or IndexedSearch.
  67.     The PBCatSearchSyncCompat function uses PBCatSearch (if available) or
  68.     IndexedSearch (if PBCatSearch is not available) to search a volume
  69.     using a set of search criteria that you specify. It builds a list of all
  70.     files or directories that meet your specifications.
  71.     
  72.     pb            input:    A CSParamPtr record specifying the volume to search
  73.                         and the search criteria.
  74.                 output:    Fields in the parameter block are returned indicating
  75.                         the number of matches found, the matches, and if the
  76.                         search ended with noErr, the CatPosition record that
  77.                         lets you resume a search where the last search left
  78.                         off.
  79.     
  80.     Note:    If you use a high-level debugger and use ioSearchTime to limit
  81.             the length of time to run the search, you'll want to step over
  82.             calls to PBCatSearchSyncCompat because it calls IndexedSearch
  83.             which installs a Time Manager task. Most high-level debuggers
  84.             don't deal gracefully with interrupt driven code.
  85.     
  86.     __________
  87.     
  88.     See also:    PBCatSearch, IndexedSearch
  89. */
  90.  
  91. /*****************************************************************************/
  92.  
  93. pascal    OSErr    NameFileSearch(StringPtr volName,
  94.                                short vRefNum,
  95.                                ConstStr255Param fileName,
  96.                                FSSpecPtr matches,
  97.                                long reqMatchCount,
  98.                                long *actMatchCount,
  99.                                Boolean newSearch,
  100.                                Boolean partial);
  101. /*    ¶ Search for files by file name with PBCatSearch.
  102.     The NameFileSearch function searches for files with a specific file
  103.     name on a volume that supports PBCatSearch.
  104.     Note: A result of catChangedErr means the catalog has changed between
  105.     searches, but the search can be continued with the possiblity that you
  106.     may miss some matches or get duplicate matches.  For all other results
  107.     (except for noErr), the search cannot be continued.
  108.  
  109.     volName            input:    A pointer to the name of a mounted volume
  110.                             or nil.
  111.     vRefNum            input:    Volume specification.
  112.     fileName        input:    The name of the file to search for.
  113.     matches            input:    Pointer to array of FSSpec where the match list is
  114.                             returned.
  115.     reqMatchCount    input:    Maximum number of matches to return    (the number of
  116.                             elements in the matches array).
  117.     actMatchCount    output: The number of matches actually returned.
  118.     newSearch        input:    If true, start a new search. If false and if
  119.                             vRefNum is the same as the last call to
  120.                             NameFileSearch, then start searching at the
  121.                             position where the last search left off.
  122.     partial            input:    If the partial parameter is false, then only files
  123.                             that exactly match fileName will be found.  If the
  124.                             partial parameter is true, then all file names that
  125.                             contain fileName will be found.
  126.  
  127.     __________
  128.     
  129.     Also see:    CreatorTypeFileSearch
  130. */
  131.  
  132. /*****************************************************************************/
  133.  
  134. pascal    OSErr    CreatorTypeFileSearch(StringPtr volName,
  135.                                       short vRefNum,
  136.                                       OSType creator,
  137.                                       OSType fileType,
  138.                                       FSSpecPtr matches,
  139.                                       long reqMatchCount,
  140.                                       long *actMatchCount,
  141.                                       Boolean newSearch);
  142. /*    ¶ Search for files by creator/fileType with PBCatSearch.
  143.     The CreatorTypeFileSearch function searches for files with a specific
  144.     creator or fileType on a volume that supports PBCatSearch.
  145.     Note: A result of catChangedErr means the catalog has changed between
  146.     searches, but the search can be continued with the possiblity that you
  147.     may miss some matches or get duplicate matches.  For all other results
  148.     (except for noErr), the search cannot be continued.
  149.  
  150.     volName            input:    A pointer to the name of a mounted volume
  151.                             or nil.
  152.     vRefNum            input:    Volume specification.
  153.     creator            input:    The creator type of the file to search for.
  154.                             To ignore the creator type, pass 0x00000000 in
  155.                             this field.
  156.     fileType        input:    The file type of the file to search for.
  157.                             To ignore the file type, pass 0x00000000 in
  158.                             this field.
  159.     matches            input:    Pointer to array of FSSpec where the match list is
  160.                             returned.
  161.     reqMatchCount    input:    Maximum number of matches to return    (the number of
  162.                             elements in the matches array).
  163.     actMatchCount    output: The number of matches actually returned.
  164.     newSearch        input:    If true, start a new search. If false and if
  165.                             vRefNum is the same as the last call to
  166.                             CreatorTypeFileSearch, then start searching at the
  167.                             position where the last search left off.
  168.  
  169.     __________
  170.     
  171.     Also see:    NameFileSearch
  172. */
  173.  
  174. /*****************************************************************************/
  175.  
  176. #ifdef __cplusplus
  177. }
  178. #endif
  179.  
  180. #endif    /* __SEARCH__ */
  181.